Add notification filter docs and update notification proto by nscuro · Pull Request #2128 · DependencyTrack/hyades

nscuro · 2026-04-17T16:13:28Z

Description

Adds notification filter docs and update notification proto.

Addressed Issue

Relates to DependencyTrack/dependency-track#3767

Additional Details

ADR PR: #2127
API server PR: DependencyTrack/hyades-apiserver#1924
Frontend PR: DependencyTrack/hyades-frontend#484

Checklist

I have read and understand the contributing guidelines
~~This PR fixes a defect, and I have provided tests to verify that the fix is effective~~
~~This PR implements an enhancement, and I have provided tests to verify that it works as intended~~
~~This PR introduces changes to the database model, and I have updated the migration changelog accordingly~~
~~This PR introduces new or alters existing behavior, and I have updated the documentation accordingly~~

Signed-off-by: nscuro <nscuro@protonmail.com>

owasp-dt-bot · 2026-04-17T16:13:41Z

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

codacy-production · 2026-04-17T16:14:34Z

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

_{TIP This summary will be updated as you push new changes. Give us feedback}

Copilot

Pull request overview

Adds documentation for notification filter expressions (CEL) and extends the notification protobuf schema to support additional notification groups/subjects and vulnerability analysis trigger metadata.

Changes:

Add “Filter Expressions” documentation page (with screenshots) and link it from the Notifications docs navigation.
Update Notifications overview docs to describe filter expressions and link to CEL.
Extend notification.proto with new notification groups/subjects and an AnalysisTrigger enum (and deprecate an older analysis-level field).

Reviewed changes

Copilot reviewed 4 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
proto/src/main/proto/org/dependencytrack/notification/v1/notification.proto	Updates notification protobuf schema (new groups/subjects, analysis trigger, deprecation) and changes Java package option.
mkdocs.yml	Adds “Filter Expressions” page to Notifications navigation.
docs/usage/notifications/overview.md	Expands alert concept docs to include filter expressions and CEL link.
docs/usage/notifications/filter-expressions.md	New documentation for CEL-based notification filtering (context, validation, examples).
docs/usage/notifications/images/filter-expression-editor.png	Screenshot for filter expression editor UI.
docs/usage/notifications/images/filter-expression-editor-error.png	Screenshot for filter expression validation errors.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-17T16:18:07Z


 option java_multiple_files = true;
-option java_package = "org.dependencytrack.proto.notification.v1";
+option java_package = "org.dependencytrack.notification.proto.v1";


Changing the proto java_package will move all generated Java classes to a new namespace, which is a source/binary breaking change for any downstream consumer of the proto artifact. It also becomes inconsistent with the existing pattern used by policy.proto (org.dependencytrack.proto.<domain>.v1). If the intent is to preserve compatibility, keep the previous java_package value; otherwise consider bumping the proto version/package (e.g., v2) and/or aligning the package naming across protos to a single convention.

Suggested change

option java_package = "org.dependencytrack.notification.proto.v1";

option java_package = "org.dependencytrack.proto.notification.v1";

Copilot · 2026-04-17T16:18:07Z

+| `BOM_VALIDATION_FAILED`                                 | [BomValidationFailedSubject](../../reference/schemas/notification.md#bomvalidationfailedsubject)                                                         |
+| `NEW_VULNERABILITY`                                     | [NewVulnerabilitySubject](../../reference/schemas/notification.md#newvulnerabilitysubject)                                                               |
+| `NEW_VULNERABLE_DEPENDENCY`                             | [NewVulnerableDependencySubject](../../reference/schemas/notification.md#newvulnerabledependencysubject)                                                 |
+| `POLICY_VIOLATION`                                      | [PolicyViolationSubject](../../reference/schemas/notification.md#policyviolationsubject)                                                                 |
+| `PROJECT_AUDIT_CHANGE`                                  | [VulnerabilityAnalysisDecisionChangeSubject](../../reference/schemas/notification.md#vulnerabilityanalysisdecisionchangesubject) or [PolicyViolationAnalysisDecisionChangeSubject](../../reference/schemas/notification.md#policyviolationanalysisdecisionchangesubject) |
+| `PROJECT_VULN_ANALYSIS_COMPLETE`                        | [ProjectVulnAnalysisCompleteSubject](../../reference/schemas/notification.md#projectvulnanalysiscompletesubject)                                         |
+| `VEX_CONSUMED`, `VEX_PROCESSED`                         | [VexConsumedOrProcessedSubject](../../reference/schemas/notification.md#vexconsumedorprocessedsubject)                                                   |


The “Subject Types” table is missing entries for newly introduced notification groups in this PR (e.g. VULNERABILITY_RETRACTED, NEW_VULNERABILITIES_SUMMARY, NEW_POLICY_VIOLATIONS_SUMMARY). Add rows for these groups and point them to their corresponding subjects so users can write filter expressions against them.

Suggested change

| `BOM_VALIDATION_FAILED` | [BomValidationFailedSubject](../../reference/schemas/notification.md#bomvalidationfailedsubject) |

| `NEW_VULNERABILITY` | [NewVulnerabilitySubject](../../reference/schemas/notification.md#newvulnerabilitysubject) |

| `NEW_VULNERABLE_DEPENDENCY` | [NewVulnerableDependencySubject](../../reference/schemas/notification.md#newvulnerabledependencysubject) |

| `POLICY_VIOLATION` | [PolicyViolationSubject](../../reference/schemas/notification.md#policyviolationsubject) |

| `PROJECT_AUDIT_CHANGE` | [VulnerabilityAnalysisDecisionChangeSubject](../../reference/schemas/notification.md#vulnerabilityanalysisdecisionchangesubject) or [PolicyViolationAnalysisDecisionChangeSubject](../../reference/schemas/notification.md#policyviolationanalysisdecisionchangesubject) |

| `PROJECT_VULN_ANALYSIS_COMPLETE` | [ProjectVulnAnalysisCompleteSubject](../../reference/schemas/notification.md#projectvulnanalysiscompletesubject) |

| `VEX_CONSUMED`, `VEX_PROCESSED` | [VexConsumedOrProcessedSubject](../../reference/schemas/notification.md#vexconsumedorprocessedsubject) |

| `BOM_VALIDATION_FAILED` | [BomValidationFailedSubject](../../reference/schemas/notification.md#bomvalidationfailedsubject) |

| `NEW_POLICY_VIOLATIONS_SUMMARY` | [NewPolicyViolationsSummarySubject](../../reference/schemas/notification.md#newpolicyviolationssummarysubject) |

| `NEW_VULNERABILITIES_SUMMARY` | [NewVulnerabilitiesSummarySubject](../../reference/schemas/notification.md#newvulnerabilitiessummarysubject) |

| `NEW_VULNERABILITY` | [NewVulnerabilitySubject](../../reference/schemas/notification.md#newvulnerabilitysubject) |

| `NEW_VULNERABLE_DEPENDENCY` | [NewVulnerableDependencySubject](../../reference/schemas/notification.md#newvulnerabledependencysubject) |

| `POLICY_VIOLATION` | [PolicyViolationSubject](../../reference/schemas/notification.md#policyviolationsubject) |

| `PROJECT_AUDIT_CHANGE` | [VulnerabilityAnalysisDecisionChangeSubject](../../reference/schemas/notification.md#vulnerabilityanalysisdecisionchangesubject) or [PolicyViolationAnalysisDecisionChangeSubject](../../reference/schemas/notification.md#policyviolationanalysisdecisionchangesubject) |

| `PROJECT_VULN_ANALYSIS_COMPLETE` | [ProjectVulnAnalysisCompleteSubject](../../reference/schemas/notification.md#projectvulnanalysiscompletesubject) |

| `VEX_CONSUMED`, `VEX_PROCESSED` | [VexConsumedOrProcessedSubject](../../reference/schemas/notification.md#vexconsumedorprocessedsubject) |

| `VULNERABILITY_RETRACTED` | [VulnerabilityRetractedSubject](../../reference/schemas/notification.md#vulnerabilityretractedsubject) |

Copilot · 2026-04-17T16:18:08Z

+  // Scheduled summary of new vulnerabilities across projects.
+  GROUP_NEW_VULNERABILITIES_SUMMARY = 23;
+
+  // Scheduled summary of new policy violations across projects.


New Group enum values are added here, but the documentation/schema reference in docs/reference/schemas/notification.md currently does not list these groups/subjects. If the schema docs are meant to be kept in sync with this proto, please regenerate/update the schema reference as part of this change so documentation consumers can discover the new notification types.

Suggested change

// Scheduled summary of new vulnerabilities across projects.

GROUP_NEW_VULNERABILITIES_SUMMARY = 23;

// Scheduled summary of new policy violations across projects.

// Scheduled summary notification for newly identified vulnerabilities

// across projects.

GROUP_NEW_VULNERABILITIES_SUMMARY = 23;

// Scheduled summary notification for newly identified policy violations

// across projects.

Add notification filter docs and update notification proto

85a9661

Signed-off-by: nscuro <nscuro@protonmail.com>

nscuro added this to the 0.7.0 milestone Apr 17, 2026

Copilot AI review requested due to automatic review settings April 17, 2026 16:13

nscuro added the documentation Improvements or additions to documentation label Apr 17, 2026

Copilot started reviewing on behalf of nscuro April 17, 2026 16:14 View session

This was referenced Apr 17, 2026

Allow notifications to be filtered using CEL expressions DependencyTrack/hyades-apiserver#1924

Merged

Add support for alert filter expressions DependencyTrack/hyades-frontend#484

Merged

nscuro merged commit 7f75112 into main Apr 17, 2026
6 of 7 checks passed

nscuro deleted the notification-filter-docs branch April 17, 2026 16:16

Copilot AI reviewed Apr 17, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add notification filter docs and update notification proto#2128

Add notification filter docs and update notification proto#2128
nscuro merged 1 commit intomainfrom
notification-filter-docs

nscuro commented Apr 17, 2026

Uh oh!

owasp-dt-bot commented Apr 17, 2026

Uh oh!

codacy-production bot commented Apr 17, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 17, 2026

Uh oh!

Copilot AI Apr 17, 2026

Uh oh!

Copilot AI Apr 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	option java_package = "org.dependencytrack.notification.proto.v1";
	option java_package = "org.dependencytrack.proto.notification.v1";

Uh oh!

Conversation

nscuro commented Apr 17, 2026

Description

Addressed Issue

Additional Details

Checklist

Uh oh!

owasp-dt-bot commented Apr 17, 2026

✅ Snyk checks have passed. No issues have been found so far.

Uh oh!

codacy-production bot commented Apr 17, 2026

Up to standards ✅

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants